.TH std::ios_base::iword 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::ios_base::iword \- std::ios_base::iword

.SH Synopsis
   long& iword( int index );

   First, allocates or resizes the private storage (dynamic array of long or another
   indexable data structure) sufficiently to make index a valid index, then returns a
   reference to the long element of the private storage with the index index.

   The reference may be invalidated by any operation on this ios_base object, including
   another call to iword(), but the stored values are retained, so that reading from
   iword(index) with the same index later will produce the same value until the next
   call to std::basic_ios::copyfmt(). The value can be used for any purpose. The index
   of the element must be obtained by a previous call to xalloc(), otherwise the
   behavior is undefined. New elements are initialized to 0.

   If the function fails (possibly caused by an allocation failure) and *this is a base
   class subobject of a basic_ios<> object or subobject, calls
   std::basic_ios<>::setstate(badbit) which may throw std::ios_base::failure.

.SH Notes

   Typical use of iword storage is to pass information (e.g. custom formatting flags)
   from user-defined I/O manipulators to user-defined operator<< and operator>> or to
   user-defined formatting facets imbued into standard streams.

.SH Parameters

   index - index value of the element

.SH Return value

   A reference to the element.

.SH Exceptions

   May throw std::ios_base::failure when setting the badbit.

.SH Example


// Run this code

 #include <iostream>
 #include <string>

 struct Foo
 {
     static int foo_xalloc;
     std::string data;

     Foo(const std::string& s) : data(s) {}
 };

 // Allocates the iword storage for use with Foo objects
 int Foo::foo_xalloc = std::ios_base::xalloc();

 // This user-defined operator<< prints the string in reverse if the iword holds 1
 std::ostream& operator<<(std::ostream& os, Foo& f)
 {
     if (os.iword(Foo::foo_xalloc) == 1)
         return os << std::string(f.data.rbegin(), f.data.rend());
     else
         return os << f.data;
 }

 // This I/O manipulator flips the number stored in iword between 0 and 1
 std::ios_base& rev(std::ios_base& os)
 {
     os.iword(Foo::foo_xalloc) = !os.iword(Foo::foo_xalloc);
     return os;
 }

 int main()
 {
     Foo f("example");
     std::cout << f << '\\n' << rev << f << '\\n' << rev << f << '\\n';
 }

.SH Output:

 example
 elpmaxe
 example

   Defect reports

   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.

     DR   Applied to         Behavior as published               Correct behavior
                     the stored value might not be         the stored value is retained
   LWG 36 C++98      retained if the reference is          until the next call of
                     invalidated                           copyfmt()
                     the function set badbit by itself on  badbit is set by basic_ios
   LWG 41 C++98      failure,                              (if *this is its base class
                     but ios_base does not provide such    subobject)
                     interface

.SH See also

            resizes the private storage if necessary and access to the void* element at
   pword    the given index
            \fI(public member function)\fP
   xalloc   returns a program-wide unique integer that is safe to use as index to
   \fB[static]\fP pword() and iword()
            \fI(public static member function)\fP
